Local API

(0 reviews)

Release Notes

Local API - Release Notes

Asset ID: local-http-rest-api | Format: OpenAPI 3.0 (YAML)


Version 4.0.3 : API Minor Updates and Examples

Released: 2026-08-15


For Integration Developers (technical)

Documentation and Validation improvements
  • Markdown styling: Updated bold text formatting in description fields from __text__ to **text** to ensure compatibility with standard Markdown renderers.
  • Error definitions: Added explicit 400 Bad Request response definitions to multiple endpoints to better document message format validation errors.
  • Display Output changes: Corrected OutputText in DisplayOutput for intermediate polling responses (HTTP 201/206) to be modeled as an array of objects ([{Text: "..."}]) instead of a simple string. Also corrected EndOfLineFlag to be a boolean true instead of a string "true".
  • Parameter updates: Changed transaction parameter ForceOffline to ProcessOffline in the offline payment example. Added CRFResult transaction parameter to the BalanceInquiryResponse to indicate request validation results.

New and updated examples

Several endpoints have new inline request/response examples to clarify complex integration flows:

  • Payment: Added PASS Loyalty Burn and PURE Loyalty Burn without PIN examples.
  • Card Acquisition: Added Card Acquisition for Payment Token request and Card Acquisition Response with Payment Token examples.
  • Balance Inquiry: Added baseline PASS Balance Inquiry and PURE Balance Inquiry requests and responses.
  • Stored Value: Added examples for prepaid mobile phone top-ups, PIN-based digital vouchers identified by EAN, and POSA requests with serial numbers.
  • Reconciliation: Updated the ReconciliationResponse example to include PaymentReceipt mock data.
  • Gift Card: Removed the hardcoded ProductType: CRFGIFTCRD from certain non-CRF Gift Card examples.

For Project Managers (non-technical summary)

Version 4.0.3 focuses on improving the quality of the API documentation without introducing new endpoints or structural breaking changes. It adds explicit documentation for standard validation errors (400 Bad Request) across the API. Additionally, this release significantly expands the library of provided examples, offering clearer guidance on how to implement specific flows such as loyalty point burns, prepaid mobile top-ups, and tokenization requests. Minor corrections were also made to the structure of display messages to accurately reflect the true behavior of the terminal.

---

Version 3.0.0 : Specification Correction Release

Released: 2026-06-13


For Integration Developers (technical)

Property naming : camelCase → PascalCase

All JSON property names across all schemas have been promoted from camelCase to PascalCase to match the Nexo wire format and the x-xml-var-name / x-json-name annotations that documented this intent in prior versions.

Scope: ~393 property names renamed across all 175 shared schemas.

Representative examples:

v2.0.x (incorrect)v3.0.0 (correct)
saleDataSaleData
paymentTransactionPaymentTransaction
messageHeaderMessageHeader
transactionIDTransactionID
timeStampTimeStamp
serviceIdServiceID
currencyCurrency

Important: The v2.0.x camelCase keys never matched what the Pay On Site terminal actually sent or accepted. Integrations that were interoperating successfully were already using PascalCase keys at the wire level.


Annotation cleanup (non-breaking)

All non-standard x-* vendor annotations have been removed from the spec:

AnnotationCount removedPurpose
x-xml-var-name597Duplicated the intended property name
x-root121XML root element hint
x-json-name20Documented the correct JSON key (now applied directly)
x-xml-text8XML text content marker
x-enum-descriptions2Enum member descriptions
x-enum-varnames2Enum code names
x-xml-content-property1XML content mapping

These annotations were only meaningful to the tooling that generated the spec. They carry no semantic meaning for REST clients.


New endpoints
EndpointMethodOperation IDDescription
/blockedGETblockedEndpointsReturns a list of endpoints currently busy with an ongoing operation
/network/configurationPOST + GETnetworkConfigurationRequest / networkConfigurationProcessingAsync endpoint to configure the terminal's LAN network parameters (IP address, gateway, subnet mask, DNS). Extension of AdminRequest; only applies if the terminal supports LAN connectivity

New functional schemas (2):

  • AdditionalAmount : represents an additional monetary amount with a Type, Identifier, and Amount. Used in MarketpayPaymentExtensions.AdditionalAmount[].
  • TransactionParameter : key/value pair (ParameterId, ParameterValue) for passing custom transaction options to the terminal. Used in MarketpayPaymentExtensions.TransactionParameters[].

New network schema (2):

  • NetworkParametersRequest : request body for /network/configuration; fields: Action, Configuration.
  • NetworkParametersConfiguration : network interface details: Interface, TerminalIPAddress, Gateway, SubnetMask, PrimaryDNS, SecondaryDNS.

Structural property changes within existing schemas

File structure change

v1.1.9 and v2.0.3 were delivered as a single monolithic YAML file (retailer_api.yaml, ~350 KB). v3.0.0 uses a split multi-file structure:

  • retailer_api.yaml : root entry point with $ref to external files
  • paths/ : 22 separate YAML files, one per endpoint
  • components/schemas/ : 204 separate YAML files, one per schema

The root file is now ~18 KB. All path and schema references use relative $ref paths. Tooling that requires a single resolved file must use an OpenAPI bundler (e.g. swagger-cli bundle) before code generation.


For Project Managers (non-technical summary)

Version 3.0.0 is a documentation correction. The previous spec (v2.0.3) contained approximately 393 field names that did not match what the payment terminal actually sends and accepts. This caused confusion for integration teams using generated clients or automated validators. Version 3.0.0 corrects these names, removes internal tooling annotations that were never intended for external consumers, and restructures the spec into separate files for easier navigation. No changes were made to the terminal software or to the Market Pay backend, the correction is purely in the API documentation. Any existing integration that is successfully processing payments is already using the correct field names at the wire level; the spec now matches that reality.

---

Version 2.0.3 : New Endpoints Release

Released: 2026-04-10

For Integration Developers (technical)

New endpoints

Three endpoints added. All follow the same async POST + GET polling pattern as /payment and /acquisition.

EndpointMethodOperation IDDescription
/activationPOST + GETActivationCommunication / ActivationProcessingTriggers a terminal activation operation. On POST, the terminal triggers it first time activation to retrieve its configuration. Poll with GET to retrieve result
/reconciliationPOST + GETreconciliationRequest / reconciliationResponseInitiates a reconciliation (batch close / totals rapprochement) between the POS and the terminal. Uses RTRReconciliationRequest / RTRReconciliationResponse
/acquisition/abortPOSTacquisitionAbortAborts a card acquisition in progress. Required for integrations that use the card-first (/acquisition → /payment) flow and need to cancel before completing payment

All three endpoints have inline request/response examples in the spec.


Schema structural changes

Three schemas were updated. These are minor corrections and do not change the required field set.

RTROutputContent.predefinedContent

  • Changed from type: array, items: $ref RTRPredefinedContent to type: object, allOf: [$ref RTRPredefinedContent]. The field now resolves as a single object rather than an array.

RTRMenuEntry.predefinedContent

  • Same correction as above : array → object allOf.

RTRDisplayOutput.menuEntry

  • The x-xml-var-name annotation corrected from DisplayOutput to MenuEntry (was a copy-paste error).

exchange.json API version

apiVersion updated from v1.1 to v1.2 in exchange.json.


No schema additions or removals

The schema component count remains 175, identical to v1.1.9. All x-* annotations are unchanged from v1.1.9.


For Project Managers (non-technical summary)

Version 2.0.3 adds three new operations to the API: terminal activation (connecting the terminal to the acquiring host), reconciliation (batch totals), and the ability to cancel an in-progress card read. These cover use cases that were already supported by the terminal hardware but not previously documented in the Exchange spec. Minor corrections were made to three data structure definitions. No existing integrations are affected by these corrections.

---

Version 1.1.9 : Baseline

Released: 2026-02-19

Initial published version of the Local API OpenAPI specification on Anypoint Exchange.

Endpoints (17): /login, /payment, /logout, /abort, /status, /diagnosis, /update, /reversal, /acquisition, /balanceinquiry, /giftcard, /cheques/payment, /cheques/reversal, /italy/voucher/payment, /italy/voucher/reversal, /italy/altpayment/payment, /italy/altpayment/reversal

Schemas: 175

Format: Single-file OAS 3.0 YAML (retailer_api.yaml)


This document was generated from analysis of the OAS files published on Anypoint Exchange. It covers changes observable in the spec files only; changes to terminal firmware or backend configuration that are not reflected in the spec are not in scope.


Reviews